(SST) ShlWAPI.pas Version 1.08

Developer Reference
(SST)ShlWAPI StrFormatByteSizeEx Function
Creates a string from an unsigned, 64-bit integer value, that is a user friendly representation of its size, expressed in either bytes, KB, MB, GB, TB, or EB.
Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).
Syntax
function StrFormatByteSizeEx(ull : ULARGE_INTEGER; flags : SFBS_FLAGS; pszBuf : LPWSTR; cchBuf : UINT) : HRESULT;  
Parameters
ull [in] The unsigned, 64-bit integer value for which a standardized size, string represntation is requested.
flags [in] Flag of type SFBS_FLAGS (= DWORD) which determines how the output should be rounded and formatted. This must be either:
SFBS_FLAGS_ROUND_TO_NEAREST_DISPLAYED_DIGIT (= $00000001)
or  
SFBS_FLAGS_TRUNCATE_UNDISPLAYED_DECIMAL_DIGITS (= $00000002)
pszBuf [out] Pointer to a null terminated buffer into which the function should write the output string.
cchBuf [in] The size, in number of double byte (i.e. Unicode) characters of the buffer pointed to by pszBuf.
Return Values
If the function succeeds, it returns S_OK (= 0), if it fails a COM/OLE error code, typically E_INVALIDARG (= $80070057).
Remarks
This function only exists in a Unicode and not, like most other ShlWAPI.dll functions, in both an ANSI and a Unicode version.
StrFormatByteSizeEx appears to have been first implemented and exported in the ShlWAPI.dll that shipped with Windows Vista. This documentation is based on that of ShlWAPi.dll version 6.0.6000.16386 (vista_rtm.061101-2205). It was not documented in any official Microsoft, offline documentation at our disposal up to and including July 05, 2023.
Unlike many other Windows API functions, the function does not return any form of information on the size of the buffer required for the output. However, as the function apparently only generates output strings that consist of a maximum of 3, possibly 4, significant digits plus a decimal separator (typically a decimal point or comma), a blank, and a size modifier consisting of two characters, an initial buffer size of 9 -10 Unicode characters (including the terminating, double byte, null character) ought to suffice in most cases.
The output generated by the function does not appear to differ significantly from that produced by StrFormatByteSize64A (which see).
To import and call the function when using the SST implementation of the ShlWAPI.pas unit, it is necessary to specify "SST_SHLWAPIVER6PT0VISTA", either in the source code or in the project settings. In the example below, the required compiler directive was specified in the first line of the source code.
Example
{$DEFINE SST_SHLWAPIVER6PT0VISTA} {$IFDEF SST_SHLWAPIVER6PT0VISTA} PROCEDURE TForm4.TestShlWAPIStrFormatByteSizeEx(Sender : TObject); VAR filehandle : HFILE; VAR sizetofmt : ULARGE_INTEGER; VAR fmtflags : SFBS_FLAGS; VAR sizestrbuf : ARRAY[0 .. 127] OF WideChar; VAR bufsize : UINT; VAR apiretval : HRESULT; VAR newinfoline : STRING; BEGIN filehandle := 0; FillChar(sizetofmt, SizeOf(sizetofmt), #0); fmtflags := 0; FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); bufsize := 0; apiretval := S_OK; //S_OK = 0 newinfoline := ''; FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); fmtflags := 0; bufsize := 0; apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); filehandle := CreateFile('C:\Windows\System32\comctl32.dll', GENERIC_READ, FILE_SHARE_READ OR FILE_SHARE_WRITE, NIL, OPEN_EXISTING, 0, 0); sizetofmt.LowPart := GetFileSize(filehandle, @sizetofmt.HighPart); newinfoline := 'StrFormatByteSizeEx called with ' + IntToStr(Int64(sizetofmt)); Memo1.Lines.Add(newinfoline); bufsize := Length(sizestrbuf); fmtflags := SFBS_FLAGS_ROUND_TO_NEAREST_DISPLAYED_DIGIT; apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); fmtflags := SFBS_FLAGS_TRUNCATE_UNDISPLAYED_DECIMAL_DIGITS; apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); CloseHandle(filehandle); FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); sizetofmt.QuadPart := $1; newinfoline := 'StrFormatByteSizeEx called with ' + IntToStr(Int64(sizetofmt)); Memo1.Lines.Add(newinfoline); bufsize := Length(sizestrbuf); fmtflags := SFBS_FLAGS_ROUND_TO_NEAREST_DISPLAYED_DIGIT; apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); sizetofmt.QuadPart := $FEDC; newinfoline := 'StrFormatByteSizeEx called with ' + IntToStr(Int64(sizetofmt)); Memo1.Lines.Add(newinfoline); bufsize := Length(sizestrbuf); fmtflags := SFBS_FLAGS_ROUND_TO_NEAREST_DISPLAYED_DIGIT; apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); sizetofmt.QuadPart := $D000CBA1; newinfoline := 'StrFormatByteSizeEx called with ' + IntToStr(Int64(sizetofmt)); Memo1.Lines.Add(newinfoline); bufsize := Length(sizestrbuf); fmtflags := 0;//Note that the flags param is set to zero ! apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); sizetofmt.QuadPart := $D000CBA1; newinfoline := 'StrFormatByteSizeEx called with ' + IntToStr(Int64(sizetofmt)); Memo1.Lines.Add(newinfoline); bufsize := Length(sizestrbuf); fmtflags := SFBS_FLAGS_ROUND_TO_NEAREST_DISPLAYED_DIGIT; apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); sizetofmt.QuadPart := $D000CBA1; newinfoline := 'StrFormatByteSizeEx called with ' + IntToStr(Int64(sizetofmt)); Memo1.Lines.Add(newinfoline); bufsize := Length(sizestrbuf); fmtflags := SFBS_FLAGS_TRUNCATE_UNDISPLAYED_DECIMAL_DIGITS; apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); sizetofmt.QuadPart := $D000CBA1; newinfoline := 'StrFormatByteSizeEx called with ' + IntToStr(Int64(sizetofmt)); Memo1.Lines.Add(newinfoline); bufsize := Length(sizestrbuf); fmtflags := SFBS_FLAGS_ROUND_TO_NEAREST_DISPLAYED_DIGIT OR SFBS_FLAGS_TRUNCATE_UNDISPLAYED_DECIMAL_DIGITS; apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); sizetofmt.QuadPart := $100F000F000F; newinfoline := 'StrFormatByteSizeEx called with ' + IntToStr(Int64(sizetofmt)); Memo1.Lines.Add(newinfoline); bufsize := Length(sizestrbuf); fmtflags := SFBS_FLAGS_ROUND_TO_NEAREST_DISPLAYED_DIGIT; apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); FillChar(sizestrbuf, SizeOf(sizestrbuf), #0); sizetofmt.QuadPart := $1000000000000000; newinfoline := 'StrFormatByteSizeEx called with ' + IntToStr(Int64(sizetofmt)); Memo1.Lines.Add(newinfoline); bufsize := Length(sizestrbuf); fmtflags := SFBS_FLAGS_ROUND_TO_NEAREST_DISPLAYED_DIGIT; apiretval := StrFormatByteSizeEx(sizetofmt, fmtflags, sizestrbuf, bufsize); newinfoline := sizestrbuf; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END; {$ENDIF}
Under Windows 10, the above example code produced the following output:
StrFormatByteSizeEx called with 573848 560 KB 560 KB StrFormatByteSizeEx called with 1 1 Bytes StrFormatByteSizeEx called with 65244 63,7 KB StrFormatByteSizeEx called with 3489713057 StrFormatByteSizeEx called with 3489713057 3,25 GB StrFormatByteSizeEx called with 3489713057 3,25 GB StrFormatByteSizeEx called with 3489713057 StrFormatByteSizeEx called with 17656611536911 16,1 TB StrFormatByteSizeEx called with 1152921504606846976 1,00 EB
Requirements
Unit: Declared and imported in (SST)ShlWAPI.pas
Library: (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode: Implemented as Unicode (StrFormatByteSizeEx) function only.
Min. ShlWAPI.dll version according to MS SDK doc.: 6.0
Min. ShlWAPI.dll version based on SST research: 6.0
Min. OS version(s) according to Microsoft SDK doc.: Windows Vista with Service Pack 1 (SP1)
Min. OS version(s) according to SST research.: Windows Vista with SP 1
See Also
SHFormatDateTime, StrFromTimeInterval, StrFormatByteSizeA, StrFormatByteSizeW, StrFormatByteSize64A, StrFormatKBSize, StrToInt, StrToInt64Ex, StrToIntEx
 
Windows APIs: SHFormatDateTime, StrFromTimeInterval, StrFormatByteSize, StrFormatByteSize64A, StrFormatByteSizeEx, StrFormatKBSize, StrToInt, StrToInt64Ex, StrToIntEx


Document/Contents version 1.00
Page/URI last updated on 07.12.2023
 
Copyright © Stoelzel Software Technologie (SST) 2010 - 2015
Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com